Компоненты в MDX

MDX сочетает возможности Markdown и JSX, позволяя встраивать компоненты React прямо в текст документации. Это открывает возможность динамического и интерактивного контента внутри Markdown-файлов, сохраняя при этом простоту разметки.

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

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


  Это предупреждение отображается прямо в MDX.

При рендеринге MDX эти компоненты обрабатываются через Remark и Rehype, которые разбирают Markdown и преобразуют его в AST (Abstract Syntax Tree). Remark отвечает за разбор и обработку Markdown, а Rehype управляет HTML-структурой, что позволяет интегрировать JSX-компоненты в дерево документа.

Подключение компонентов

MDX предоставляет возможность глобально регистрировать компоненты через объект MDXProvider. Все элементы, переданные в components, автоматически подменяют стандартные теги Markdown.

import { MDXProvider } from '@mdx-js/react'
import { Heading, Paragraph } from './ui'

const components = {
  h1: Heading,
  p: Paragraph
}

Особенности:

  • Любой стандартный тег Markdown можно заменить на собственный компонент.
  • Компоненты могут использоваться рекурсивно внутри других компонентов, создавая сложные структуры документации.
  • Передаваемые пропсы позволяют полностью кастомизировать внешний вид и поведение.

Интеграция с Remark и Rehype

Remark и Rehype работают как плагины для трансформации AST:

  • Remark-плагины выполняют работу на уровне Markdown: анализируют заголовки, ссылки, списки, вставляют дополнительные элементы и даже модифицируют текст.
  • Rehype-плагины обрабатывают HTML-представление документа: добавляют атрибуты, стили, создают интерактивные элементы и оптимизируют структуру DOM.

Пример подключения плагинов:

import remarkGfm from 'remark-gfm'
import rehypeSlug from 'rehype-slug'
import { compile } from '@mdx-js/mdx'

const mdxSource = `
# Заголовок
Текст с **выделением** и ссылкой [MDX](https://mdxjs.com/)
`

const compiled = await compile(mdxSource, {
  remarkPlugins: [remarkGfm],
  rehypePlugins: [rehypeSlug],
  jsx: true
})

Ключевые моменты:

  • remarkGfm добавляет поддержку GitHub-flavored Markdown (таблицы, чекбоксы, автолинкование).
  • rehypeSlug создаёт уникальные идентификаторы для заголовков, что облегчает навигацию.
  • Опция jsx: true позволяет встраивать React-компоненты прямо в Markdown.

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

MDX позволяет передавать в компоненты произвольные пропсы, включая функции, объекты и состояния React.

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

Также возможна динамическая подгрузка компонентов с использованием React.lazy и Suspense, что особенно полезно для больших документаций или ленивой загрузки интерактивных блоков:

import { Suspense, lazy } from 'react'

const Chart = lazy(() => import('./components/Chart'))

Загрузка графика...
}>

Кастомизация рендеринга

MDX предоставляет API для тонкой настройки рендеринга:

  • Обёртка контента: позволяет создавать единый стиль для всех элементов документации.
  • Комбинация с CSS-in-JS: все компоненты могут использовать стили через styled-components или emotion.
  • Условный рендеринг: можно создавать контент, который отображается только при определённых условиях (например, в зависимости от пользовательских данных или состояния приложения).
const components = {
  p: (props) => 

}

Работа с деревом AST

Для сложных трансформаций MDX предоставляет доступ к AST:

  • Remark AST (MDAST): структура, которая отражает исходный Markdown. Позволяет писать плагины для модификации заголовков, текста, вставки компонентов.
  • Rehype AST (HAST): дерево HTML. Используется для оптимизации, добавления атрибутов и стилизации.

Пример добавления класса ко всем параграфам через Rehype-плагин:

function rehypeAddClass() {
  return (tree) => {
    visit(tree, 'element', (node) => {
      if (node.tagName === 'p') {
        node.properties.className = (node.properties.className || []).concat('custom-paragraph')
      }
    })
  }
}

Синхронизация Markdown и React

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

  • Статический текст сохраняет SEO-дружелюбность и лёгкость чтения.
  • Компоненты React добавляют интерактивность и динамическое поведение.
  • Remark и Rehype обеспечивают гибкую трансформацию контента на этапе компиляции, поддерживая масштабируемость и повторное использование компонентов.
Оглавление