Встраивание JSX компонентов

MDX — это расширение Markdown, которое позволяет использовать JSX внутри текстовых документов. Основная цель MDX — объединить возможности разметки Markdown с динамическими компонентами React, что делает его идеальным для создания интерактивной документации, блогов и образовательных материалов. Встраивание JSX компонентов является центральной концепцией, которая раскрывает весь потенциал MDX.

Синтаксис вставки компонентов

В MDX любой React-компонент можно использовать как обычный HTML-тег:

Здесь Button — это React-компонент, импортированный в файл MDX. Главное отличие от стандартного JSX в том, что в MDX можно свободно сочетать разметку Markdown с компонентами:

# Заголовок

Некоторый текст с интерактивной кнопкой:



Продолжаем текст после кнопки.

MDX распознаёт JSX-подобные теги и рендерит их как компоненты, а текстовые блоки Markdown остаются неизменными.

Импорт и использование компонентов

Компоненты React нужно импортировать в MDX-файл так же, как в обычный .jsx или .tsx файл. Например:

import { Alert, Card } from './components';

Внимание! Это важное уведомление.


  Содержимое карточки может включать любые JSX элементы.

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

Передача props и children

Любые свойства (props) можно передавать компонентам напрямую. При этом MDX позволяет комбинировать строки Markdown с JSX, например:


  Этот компонент может содержать **Markdown-разметку** внутри JSX.

Внутри тега можно использовать Markdown-синтаксис, который будет корректно рендериться. Это особенно полезно для создания компонентов документации, где текст может быть отформатирован без потери динамики.

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

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

const features = [
  { name: "Скорость", description: "Обрабатывает данные мгновенно" },
  { name: "Гибкость", description: "Легко настраивается под задачи" },
];

{features.map((feature, index) => (
  
    {feature.description}
  
))}

Это позволяет создавать интерактивные списки, таблицы, галереи и другие элементы интерфейса прямо внутри MDX.

Встраивание компонентов с условиями

MDX позволяет использовать условный рендеринг, так же как в React:

{isLoggedIn ? (
  
) : (
  
)}

Благодаря этому можно менять содержимое документа в зависимости от состояния приложения или контекста пользователя.

Контекст и провайдеры

MDX может использовать React-контекст и провайдеры для передачи данных внутрь компонентов:

import { ThemeProvider } from './theme-context';


  Нажми меня

Все компоненты внутри будут иметь доступ к текущей теме. Это особенно полезно при создании документации с темами, интерактивных демо-компонентов и примерного кода.

Встраивание HTML-атрибутов и inline-компонентов

MDX позволяет использовать стандартные HTML-атрибуты внутри компонентов и даже создавать компоненты прямо в тексте:

Текст с кнопкой  прямо в предложении.

Такой подход позволяет сохранять поток текста, не прерывая его блоками JSX, что делает документацию более естественной и читаемой.

Использование MDX с TypeScript

MDX полностью совместим с TypeScript. Для этого используется расширение .mdx в сочетании с настройкой TypeScript и React. Например:

import { Alert } from './components';

type AlertProps = {
  type: 'success' | 'warning' | 'error';
  children: React.ReactNode;
};

Это сообщение об успехе

TypeScript помогает выявлять ошибки в props и поддерживает автодополнение при работе с компонентами MDX.

Примеры комплексного использования

MDX отлично подходит для интерактивной документации:

import { Tabs, Tab } from './components';


  
    {`Hello
`}
  
  
    {`Hello
`}
  



  Использование вкладок позволяет демонстрировать различные варианты кода без перегруженности страницы.

В этом примере комбинируются динамические компоненты, Markdown и JSX для удобного отображения информации.