Приоритеты и переопределение компонентов

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

1. Основные принципы рендеринга компонентов

В MDX каждый элемент Markdown может быть представлен соответствующим React-компонентом. Например:

# Заголовок первого уровня

По умолчанию рендерится как

в HTML. MDX использует систему приоритетов, где пользовательские компоненты имеют возможность переопределять стандартные элементы Markdown.

Порядок приоритета рендеринга:

  1. Локальные переопределения компонентов — компоненты, переданные через components при импорте MDX.
  2. Компоненты из темы или глобальные настройки — переопределения, заданные через MDXProvider в React.
  3. Стандартные HTML-компоненты, соответствующие Markdown-элементам (h1, p, ul и т.д.).

Это значит, что любой компонент, переданный через components при рендеринге MDX-файла, имеет наивысший приоритет и заменяет дефолтный рендерер.

2. Использование MDXProvider для глобальных переопределений

MDXProvider позволяет определять глобальные переопределения компонентов, которые применяются ко всем MDX-документам в приложении.

Пример:

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

const components = {
  h1: (props) => 
,
  p: (props) => 

};

function App() {
  return (
    
      
    
  );
}

В этом примере все заголовки

в MDX-документах будут красного цвета, а параграфы получат класс custom-paragraph. Если в конкретном MDX-файле передан локальный компонент h1, он перекроет глобальное переопределение.

3. Локальные переопределения компонентов

MDX позволяет передавать переопределения напрямую при рендеринге конкретного документа:

import Content from './Content.mdx';

const localComponents = {
  h1: (props) => 

};

function Page() {
  return ;
}

Здесь для данного MDX-файла заголовки

будут отображаться с увеличенным размером шрифта, не затрагивая другие MDX-документы, использующие глобальные переопределения через MDXProvider.

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

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

  • Заголовки (h1–h6)
  • Абзацы (p)
  • Списки (ul, ol, li)
  • Ссылки (a)
  • Изображения (img)
  • Блоки кода (pre, code)

Пример замены параграфа на компонент с анимацией:

const AnimatedParagraph = ({ children }) => (
  
{children}

);

const components = { p: AnimatedParagraph };

После этого все абзацы в MDX-документе будут рендериться через AnimatedParagraph.

5. Приоритеты вложенных компонентов

При работе с MDX важно учитывать вложенные компоненты:

  • Если компонент использует внутри себя

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

  • Если импортируется как обычный React-компонент и рендерится вне MDX, глобальные переопределения не применяются автоматически, требуется передача components вручную.

6. Комбинирование глобальных и локальных компонентов

MDX поддерживает композицию переопределений:

const globalComponents = { p: GlobalParagraph };
const localComponents = { h1: LocalHeading };

В этом случае:

  • → используется локальный LocalHeading

  • → используется глобальный GlobalParagraph

  • Любые другие теги → стандартные HTML-рендереры

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

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

  • Всегда определять глобальные компоненты через MDXProvider, если требуется единый стиль для всех документов.
  • Использовать локальные компоненты для индивидуальных настроек конкретного MDX-файла.
  • Не путать JSX-компоненты с HTML-тегами, поскольку MDX рассматривает все Markdown-теги как React-компоненты и применяет приоритеты в порядке локального → глобального → стандартного.
  • Для больших проектов рекомендуется создать библиотеку базовых компонентов, которые можно переопределять в MDXProvider, что упрощает поддержку и масштабирование документации.

8. Подводные нюансы

  1. Контекст MDX не передается через обычный JSX. Для компонентов, используемых вне MDX, требуется оборачивать их в MDXProvider.
  2. Переопределение встроенных HTML-элементов может повлиять на SEO и доступность, поэтому важно сохранять семантику (h1–h6, p, ul и т.д.).
  3. Для динамического выбора компонентов на основе данных можно использовать функцию-обертку, возвращающую компонент:
const components = {
  p: (props) => (props.warning ?  : 
)
};

Это позволяет реализовать умные и контекстно-зависимые переопределения.

Оглавление