Композиция контента

MDX (Markdown + JSX) объединяет привычный синтаксис Markdown с возможностями JSX, позволяя внедрять React-компоненты прямо в текстовый контент. Это даёт гибкость при создании документации, блогов и интерактивных интерфейсов. Основная идея — возможность использования компонентов для динамического или структурного контента без отказа от привычного Markdown.

Простейший пример MDX:

# Заголовок

Текст с обычным Markdown.

<MyComponent someProp="value" />

Здесь MyComponent — обычный React-компонент, который можно вставить между параграфами, списками или таблицами.

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

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

<Button variant="primary" onCl ick={() => alert('Clicked!')}>
  Нажми меня
</Button>

Можно также использовать локальные компоненты, объявленные прямо внутри MDX-файла:

export const Highlight = ({ children }) => <span style={{ color: 'red' }}>{children}</span>

Это <Highlight>важное</Highlight> слово.

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

Импорт и экспорт модулей

MDX-файлы могут импортировать компоненты и данные из внешних модулей:

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

<Alert type="warning">Это предупреждение</Alert>
<CodeBlock language="js">{`console.log('Пример');`}</CodeBlock>

Также MDX поддерживает экспорт для использования данных или функций внутри других компонентов:

export const title = "MDX Статья"

Использование JSX в Markdown-блоках

MDX позволяет смешивать JSX с Markdown:

# Заголовок

Некоторый текст с **Markdown**.

<div style={{ border: '1px solid black', padding: '10px' }}>
  Это блок, оформленный через JSX
</div>

Важно учитывать, что Markdown-блоки преобразуются в JSX, поэтому не допускаются несовместимые конструкции, такие как вложенные <p> в <p>.

Разметка и стилизация контента

MDX поддерживает стандартные HTML-теги, CSS-in-JS и стили через пропсы. Это позволяет создавать гибкую визуальную композицию:

<Card style={{ padding: '20px', backgroundColor: '#f5f5f5' }}>
  <h2>Заголовок карты</h2>
  <p>Описание содержимого</p>
</Card>

Для глобального оформления можно использовать темы, контекст или стилизованные компоненты.

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

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

import { ThemeContext } from './ThemeContext'

<ThemeContext.Provider value={{ theme: 'dark' }}>
  <ThemedComponent />
</ThemeContext.Provider>

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

Навигация и структура документа

MDX поддерживает структурирование контента через заголовки, списки и вложенные компоненты. Можно создавать сложные страницы с многоуровневой навигацией:

# Глава 1

<Section title="Подраздел 1.1">
  Контент подраздела
</Section>

<Section title="Подраздел 1.2">
  Другой контент
</Section>

Компоненты типа <Section> могут автоматически формировать оглавление, индекс или динамические ссылки на разделы.

Интерактивные примеры и редакторы кода

MDX отлично сочетается с библиотеками типа react-live, позволяя встраивать интерактивные редакторы кода:

import { LiveProvider, LiveEditor, LivePreview } from 'react-live'

<LiveProvider code={`<button>Click me</button>`}>
  <LiveEditor />
  <LivePreview />
</LiveProvider>

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

Практические рекомендации

  • Разделять визуальные компоненты и текстовый контент для удобства поддержки.
  • Использовать импорты и экспорт данных для единообразия и повторного использования.
  • Следить за правильной вложенностью JSX внутри Markdown.
  • Применять CSS-in-JS или стилизованные компоненты для единообразного оформления.
  • Использовать контекст и состояния для интерактивных элементов, не нагружая глобальную логику страницы.

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

Оглавление