Опции конфигурации

MDX — это расширение синтаксиса Markdown, позволяющее внедрять JSX-компоненты прямо в текст. Для полноценного использования MDX важно понимать возможности конфигурации библиотеки, которые позволяют управлять процессом компиляции, интеграцией с React-компонентами и обработкой контента.

remarkPlugins и rehypePlugins

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

  • remarkPlugins: массив плагинов для обработки AST Markdown перед компиляцией в HTML/JSX. Примеры:

    • remark-slug — автоматически добавляет id к заголовкам.
    • remark-autolink-headings — генерирует ссылки на заголовки.

  • rehypePlugins: массив плагинов для обработки AST HTML. Примеры:

    • rehype-highlight — подсветка синтаксиса для блоков кода.
    • rehype-katex — рендеринг математических выражений в формате LaTeX.

Применение этих плагинов обеспечивает гибкость в преобразовании контента MDX до финального JSX.

providerImportSource

Опция providerImportSource позволяет задать модуль, из которого будет импортироваться контекстный провайдер для обертки MDX-контента. Это особенно полезно, когда нужно использовать темы, локализацию или глобальные состояния через React Context.

Пример использования:

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

const components = {
  h1: (props) => <h1 style={{ color: 'tomato' }} {...props} />,
};

<MDXProvider components={components}>
  <MDXContent />
</MDXProvider>

Установка providerImportSource гарантирует, что MDXProvider будет корректно подключен при компиляции.

jsxImportSource

Опция jsxImportSource позволяет указать модуль для JSX-функций (jsx, jsxs, Fragment), который будет использоваться MDX при трансформации. Обычно используется в сочетании с Emotion или Stitches для CSS-in-JS.

Пример:

export const jsxImportSource = '@emotion/react';

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

format

Параметр format управляет исходным синтаксисом MDX-файла:

  • 'md' — строгий Markdown без JSX.
  • 'mdx' — Markdown с возможностью использования JSX.

Эта настройка важна при интеграции MDX в проекты, где часть контента должна оставаться чистым Markdown.

provider

Опция provider используется для передачи компонента-обертки через конфигурацию MDX. Позволяет оборачивать весь контент в нужный React-компонент, не добавляя обертку вручную в каждом файле.

Пример:

import Layout from './Layout';

export const MDXComponents = {
  wrapper: Layout,
};

Все MDX-документы будут автоматически обернуты в <Layout>.

remarkRehypeOptions

Эта опция позволяет передавать параметры напрямую в конвертер remark -> rehype. Например, можно отключить обработку HTML или управлять пропуском пустых узлов.

{
  remarkRehypeOptions: { allowDangerousHtml: true }
}

development и jsx в конфигурации

  • development: флаг, включающий детальную проверку ошибок при компиляции MDX.
  • jsx: управляет генерацией кода JSX. Можно включить automatic для автоматического импорта функций JSX.

skipExport и outputFormat

  • skipExport: предотвращает автоматический экспорт MDXContent. Используется в случаях, когда нужен кастомный экспорт или интеграция с системой маршрутизации.
  • outputFormat: определяет формат выходного кода (function-body или program), что важно для совместимости с различными сборщиками.

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

Для серверной генерации или динамического рендеринга MDX используется MDXRemote с отдельной конфигурацией:

import { MDXRemote } from 'next-mdx-remote';

<MDXRemote {...source} components={components} />

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

Практические советы по конфигурации

  • Всегда группировать плагины в массивы и проверять их порядок — remarkPlugins выполняются до rehypePlugins.
  • Для кастомных компонентов использовать объект components вместо глобальных правок JSX, чтобы избежать конфликтов.
  • В сложных проектах с CSS-in-JS или темами лучше указывать jsxImportSource и providerImportSource, чтобы поддерживать консистентность и интеграцию с React Context.
  • Проверять совместимость плагинов с версией MDX — некоторые плагины ориентированы на MDX v1 или v2, что может вызвать ошибки компиляции.

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

Оглавление