Проверка работоспособности

MDX — это расширение Markdown, позволяющее включать JSX-компоненты прямо в тексте. Для начала работы необходимо установить соответствующие пакеты:

npm install @mdx-js/react @mdx-js/loader

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

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

const components = {
  h1: MyCustomH1,
};

function App({ children }) {
  return (
    <MDXProvider components={components}>
      {children}
    </MDXProvider>
  );
}

Настройка сборщика для MDX

Для работы MDX с Webpack требуется добавить загрузчик:

module.exports = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          'babel-loader',
          '@mdx-js/loader'
        ]
      }
    ]
  }
};

Для Vite достаточно использовать официальный плагин @mdx-js/rollup:

import mdx from '@mdx-js/rollup';

export default {
  plugins: [
    mdx()
  ]
};

Создание и импорт MDX-файлов

Файл с расширением .mdx может содержать как обычный Markdown, так и JSX. Например:

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

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

<MyComponent prop="value" />

Импорт MDX в React-компонент выглядит так:

import Content from './example.mdx';

function Page() {
  return <Content />;
}

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

Проверка работоспособности

Чтобы убедиться, что MDX работает корректно, следует выполнить несколько проверок:

  1. Отображение Markdown Создать простую MDX-страницу с заголовком, абзацем и списком. Если все элементы рендерятся корректно, базовая интеграция работает.
# Тестовый заголовок

- Пункт 1
- Пункт 2
- Пункт 3
  1. Отображение JSX-компонентов Включить компонент в MDX и проверить его рендер:
<MyTestComponent text="MDX работает" />

Если компонент отобразился, значит MDX правильно интерпретирует JSX.

  1. Проверка передачи пропсов Передать параметры в компонент через MDX и убедиться, что они корректно применяются:
<MyTestComponent title="Пропс заголовка" count={5} />

В React-компоненте следует проверить значения props.title и props.count.

  1. Стилизация и кастомизация компонентов Для проверки применения кастомных компонентов через MDXProvider:
const components = {
  h1: ({ children }) => <h1 style={{ color: 'red' }}>{children}</h1>
};

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

Отладка ошибок

Чаще всего ошибки при работе с MDX связаны с:

  • Неправильной конфигурацией сборщика — необходимо убедиться, что babel-loader и @mdx-js/loader установлены и прописаны корректно.
  • Ошибками JSX внутри MDX — JSX должен быть корректным и оборачиваться в скобки при необходимости.
  • Несовпадением версий — важно, чтобы версии @mdx-js/react и @mdx-js/loader соответствовали друг другу и проекту React.

Автоматическая проверка

Для CI/CD можно настроить простые тесты рендеринга MDX:

import { render } from '@testing-library/react';
import Content from './example.mdx';

test('MDX рендерится без ошибок', () => {
  const { getByText } = render(<Content />);
  expect(getByText('Тестовый заголовок')).toBeInTheDocument();
});

Такой тест гарантирует, что изменения в MDX-файлах не ломают отображение приложения.

Логирование и консоль

Для промежуточной проверки можно добавлять простое логирование пропсов или состояния:

<MyTestComponent text="Проверка" onCl ick={() => console.log('Клик')} />

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

Итоговая проверка

После настройки всех компонентов, сборщика и провайдера, тестирование MDX должно включать:

  • Рендер Markdown
  • Рендер JSX
  • Передачу пропсов
  • Стилизацию через MDXProvider
  • Проверку сборки через CI/CD
  • Консольное логирование для отладки

Такой подход позволяет гарантировать стабильную работу MDX в любом React-проекте и выявлять ошибки на раннем этапе.

Оглавление